feat: Add ability to download specific tool versions used by hooks. TLDR: add --hook-config=--tool-version=1.2.3 for pinning wrapped tool version. Works for all tools (even terraform and tofu) except checkov - #1002

• This PR introduces breaking change.
• This PR fixes a bug.
• This PR adds new functionality.
• This PR enhances existing functionality.

Description of your changes

What

_{This section was generated by AI.}

• Adds --hook-config=--tool-version=X.Y.Z version pinning to every hook that wraps a downloadable release binary (terraform_tflint, terraform_docs, terraform_tfsec/terraform_trivy, terrascan, infracost_breakdown, tfupdate, terragrunt_*, and Terraform/OpenTofu via terraform_validate/terraform_fmt/terraform_providers_lock), resolved and cached on demand by invoking the existing tools/install/<tool>.sh installer scripts - opt-in, zero effect on hooks that don't set it.
• Adds --hook-config=--tool-version-mode=strict|prefer-local to control whether a pinned version always wins (strict, default) or an already-on-$PATH binary is preferred when present (prefer-local).
• On terraform_validate/terraform_fmt/terraform_providers_lock, --tf-path can now also be set to the literal value terraform, opentofu, or tofu (instead of an actual binary path) when combined with --tool-version, to explicitly pick which of the two to pin rather than relying on $PATH-based auto-detection.
• Adds an actionable error (naming the missing tool and the hook, suggesting --hook-config=--tool-version=) when a hook's tool is neither pinned nor found on $PATH, instead of deferring to a generic "command not found" failure later.
• checkov/terraform_checkov is explicitly excluded (pip-distributed, not a GitHub-release binary - forcing it through this path would fight its actual, already-working distribution model).
• New README.md section documenting usage, a cache-directory-mounting note for persisting across Docker container runs, and a Renovate customManagers recipe for keeping pins auto-bumped.
• Updates .github/CONTRIBUTING.md's "Add new hook" checklist to mention the new runtime call site alongside the existing Docker build-time one.
• One small, backward-compatible change to tools/install/_common.sh: source /.env is now conditional on the file existing, so the installer scripts also run correctly when invoked directly at hook run-time (not just inside a Docker build).
• Fixes a bug where a failed tool resolution (common::resolve_tool_path) was silently swallowed by local -r tool_path=$(...), letting terraform_tflint, terraform_docs, infracost_breakdown, and the shared per_dir_hook continue with an empty tool path instead of aborting with the resolver's own error message.
• Corrects stale tool_path doc comments left over from the tf_path->tool_path rename in 9 hooks, and fixes invalid YAML indentation in 3 --tool-version README examples.
• Fixes terragrunt_validate/terragrunt_validate_inputs/terragrunt_fmt/terragrunt_providers_lock picking their pre/post-0.78 CLI syntax off whatever terragrunt is on $PATH instead of the resolved/pinned tool_path binary that actually runs - a pinned version on the other side of the 0.78 boundary from $PATH picked the wrong syntax and broke.
• Fixes 5 bugs flagged by Copilot's automated review (#4992979471): prefer-local mode probed opentofu on $PATH instead of the real tofu binary so the pin always won regardless of mode; the published Docker image had no curl, breaking cache-miss downloads; terrascan's installer used bash4-only ${TARGETOS^}, breaking under macOS's bash 3.2; the cache key omitted OS/arch, so a cache dir shared across platforms (e.g. a Docker volume mount) could serve an incompatible binary as a false hit; and specific-version resolution only searched GitHub's unpaginated, 30-release page, so pinning anything older silently failed.
• Wires hcledit through the same resolver for terraform_wrapper_module_for_each - the last release-binary hook --tool-version didn't yet cover.
• Fixes the Docker cache-mount README example, which mounted under /root while also dropping to a non-root USERID (unreachable, permission denied).
• Silences a hadolint DL3064 false positive on the pre-existing ARG GITHUB_TOKEN/ENV INFRACOST_API_KEY (both empty-default placeholders, real values supplied externally, never hardcoded).
• Fixes CI Docker buildx builds failing with e.g. tflint.sh ... exit code: 3: build-image.yaml/build-image-test.yaml passed GITHUB_TOKEN via buildx secrets:, which nothing in the Dockerfile mounts - dead config left over from before --build-arg-based GitHub API auth was added, so every image build resolved tool versions via unauthenticated (60/hr, shared across all Actions runners) GitHub API calls. Now passed as a GITHUB_TOKEN build-arg, matching what tools/install/_common.sh already expects.

Why

This enables multi-version testing and the ability to pin the same versions of underlying tools by users, which is a decent improvement towards reproducibility.

Fix: #188, #270, #1009
Related: #722

How can we test changes

_{This section was generated by AI.}

- id: terraform_tflint
  args:
    - --hook-config=--tool-version=0.50.0

Run pre-commit run terraform_tflint - first run downloads and caches tflint 0.50.0 into $XDG_CACHE_HOME/pre-commit-terraform (or $HOME/.cache/pre-commit-terraform), subsequent runs hit the cache with no network call. Same pattern works for terraform_validate/terraform_fmt/terraform_providers_lock (pins Terraform/OpenTofu), optionally combined with --hook-config=--tf-path=opentofu to force OpenTofu specifically regardless of what's on $PATH.

Assisted-by

_{Specific models used per commit are specified in the commit messages.}

• Assisted-by: Sisyphus:claude-sonnet-5 opencode (b85f444, a5e62cc, a432cff, a475d47, 7892df6, 277e7cd, fb8c3f8)
• Assisted-by: Sisyphus:claude-sonnet-5 claude (869f6b6)